home *** CD-ROM | disk | FTP | other *** search
/ Cream of the Crop 25 / Cream of the Crop 25.iso / bbs / con_005c.zip / CONCORD.RAR / SCRIPT.DOC < prev    next >
Text File  |  1997-04-25  |  13KB  |  373 lines
  1.   --- Information about Concord Script Language ----------------------[ 1/8 ]--
  2.  
  3.  
  4.   Lines marked with "|" represent changes since previous version.
  5.  
  6.   Introduction :
  7.  
  8.           Concord Script Language is very powerful way of writing own
  9.           additions to the software itself. Syntax is something between
  10.           Basic and Pascal without type and range checking which makes it
  11.           closer to C language, because all responsibility is left for the
  12.           author. Script files are interpreted on the run and they need
  13.           not to be compiled before use.
  14.  
  15. |         Script language will be enhanced later, providing more syntax
  16. |         checking and more flexibility than the current way provides.
  17.  
  18.   Some features :
  19.  
  20.           - single type variables (string, number, date)
  21.           - mathematical formulas
  22.           - arithmetical operations
  23.           - string handling commands
  24.           - IF-THEN-ELSE construction
  25.           - sub-routines: functions and procedures
  26.           - various units
  27.           - run external programs
  28.           - run Concord menutypes
  29.           - redirectable output
  30.           - scripts can be edited with any ASCII editor
  31.  
  32.   Reserved words :
  33.  
  34.           - commands :
  35.  
  36.             GOTO     GOSUB    RETURN   QUIT     CALL     EXIT
  37.             VAR      SET      WRITE    OUTPUT   EXEC     MENUTYPE
  38.             IF       ELSE     END      PARAM    INPUT    ALLPARAM
  39.  
  40.           - variable types :
  41.  
  42.             ARRAY    STRING   NUMBER   DATE     TIME     DATETIME
  43.  
  44.           - string handling :
  45.  
  46.             STRLEN   STRCPY   STRDEL   STRPOS   STRINS   RANDOM
  47.  
  48.           - macros :
  49.  
  50.             @ANSWER@ + all valid Concord macro codes (@XXX@)
  51.   
  52.   --- Information about Concord Script Language ----------------------[ 2/8 ]--
  53.  
  54.  
  55.   General :
  56.  
  57.           - Default script file extension is .Q-A, scripts are searched
  58.             from Concord system path.
  59.  
  60.           - No limitations concerning number of variables, subroutines and
  61.             units
  62.  
  63.           - Max line length is 255 (in expanded format, which means after
  64.             macro codes have been converted)
  65.  
  66.           - Remark and comment lines start with semicolon character, ie.
  67.             ";anything possible here"
  68.  
  69.           - Variables are identified with percent signs, ie.
  70.             "%THIS_IS_VARIABLE%"
  71.  
  72.           - Variables must be assigned to some type before use, ie.
  73.             "VAR %variable% = NUMBER"
  74.  
  75.           - All variables are global which means that they can be
  76.             referenced anywhere in script even if assigned in subroutine.
  77.  
  78.           - Subroutine labels are defined like in DOS batch files, ie.
  79.             ":THIS_IS_LABEL"
  80.  
  81.           - Subroutine parameters must be assigned to some type in
  82.             beginning of each subroutine, ie.
  83.             "PARAM %parameter% = NUMBER" or
  84.             "ALLPARAM %parameter% = STRING"
  85.  
  86.           - Parenthesis must be used in comparisons, ie.
  87.             "IF (variable1 = variable2)" or "IF ((a = b) OR (a = c))"
  88.  
  89.           - All commands must be on separate lines and cannot be divided
  90.             into several lines.
  91.   
  92.   --- Information about Concord Script Language ----------------------[ 3/8 ]--
  93.  
  94.  
  95.   Command usage :
  96.  
  97.           GOTO <label> [<parameters>]
  98.           GOSUB <label> [<parameters>]
  99.           RETURN
  100.           PARAM %variable% = type
  101.           ALLPARAM %variable% = STRING 255
  102.  
  103.                   GOTO and GOSUB jumps into subroutine <label> with given
  104.                   parameters. In GOTO, it is not possible to return back
  105.                   to original position in script without another GOTO
  106.                   command. In GOSUB, RETURN continues execution from
  107.                   original position. PARAM defines subroutine parameters
  108.                   and their types. This must be done in beginning of
  109.                   subroutine. In STRING types, max length must also be
  110.                   specified. ALLPARAM assigns all the remaining subroutine
  111.                   parameters to the string variable (parameter list is not
  112.                   emptied).
  113.  
  114.                   Example :
  115.  
  116.                       GOTO main
  117.  
  118.                     :greet
  119.                       ALLPARAM %paramlist% = STRING 255
  120.                       PARAM %firstname% = STRING 15
  121.                       PARAM %lastname%  = STRING 15
  122.                       PARAM %seclvl%    = NUMBER
  123.                       write "Debug: parameter list = %paramlist%^M;"
  124.                       write "^C14,0;Hello, %firstname%! Let me guess, your "
  125.                       write "security level is... %seclvl%, isn't it?^M;^M;"
  126.                       RETURN
  127.  
  128.                     :demo
  129.                       write "^C13,0;No parameters for this sub-routine.^M;^M;"
  130.                       RETURN
  131.  
  132.                     :main
  133.                       GOSUB greet @name@ @seclvl@
  134.                       GOSUB demo
  135.                       quit
  136.  
  137.           QUIT
  138.  
  139.                   QUIT ends script and returns to Concord.
  140.   
  141.   --- Information about Concord Script Language ----------------------[ 4/8 ]--
  142.  
  143.  
  144.           CALL <scriptfile>
  145.           EXIT
  146.  
  147.                   CALL jumps into another script file. EXIT returns back
  148.                   to caller script.
  149.  
  150.           VAR %variable% = type
  151.           SET %variable% = <newvalue>
  152.           SET @macro@ = <newvalue>
  153.  
  154.                   VAR assigns variable to type. This must be done before
  155.                   variable is used. In STRING types, max length must also
  156.                   be specified. Arithemetical operations and string
  157.                   handling commands are allowed with SET command.
  158.  
  159.                   Arithmetical operations :
  160.  
  161.                     [ (SHL)    ] (SHR)    | (OR)     & (AND)    ^ (XOR)
  162.                     $ (MOD)    * (MUL)    / (DIV)    + (ADD)    - (DEC)
  163.  
  164.                     Parenthesis are allowed and will normally affect to
  165.                     calculation order, ie. 2+3*5=17 but (2+3)*5=25
  166.  
  167.                   Special commands :
  168.  
  169.                     RANDOM <max>
  170.  
  171.                     returns random value from 0 to max-1, ie. RANDOM 100
  172.                     ==> 0..99
  173.  
  174.                   String handling commands :
  175.  
  176.                     STRLEN <str>
  177.  
  178.                     returns length of string <str>, ie. STRLEN pasi = 4
  179.  
  180.                     STRCPY <pos> <len> <str>
  181.  
  182.                     copies <len> chars from position <pos> in string
  183.                     <str>, ie. STRCPY 6 5 talliniemi = niemi
  184.  
  185.                     STRDEL <pos> <len> <str>
  186.  
  187.                     deletes <len> chars from position <pos> in string
  188.                     <str>, ie. STRDEL 6 5 talliniemi = talli
  189.  
  190.                     STRPOS <searchstr> # <str>
  191.  
  192.                     returns position of first occurrence of string
  193.                     <searchstr> in string <str>, ie. STRPOS niemi #
  194.                     talliniemi = 6
  195.   
  196.   --- Information about Concord Script Language ----------------------[ 5/8 ]--
  197.  
  198.  
  199.                     STRINS <pos> <ins> # <str>
  200.  
  201.                     inserts string <ins> to position <pos> in string
  202.                     <str>, ie. STRINS 3 s # pai = pasi
  203.  
  204. |                   STRUPP <str>
  205. |
  206. |                   converts string <str> to uppercase, ie. STRUPP
  207. |                   talliniemi = TALLINIEMI
  208. |
  209. |                   STRLOW <str>
  210. |
  211. |                   converts string <str> to lowercase, ie. STRLOW
  212. |                   TALLINIEMI = talliniemi
  213. |
  214. |                   STRCAP <str>
  215. |
  216. |                   converts first char of each word in string <str> to
  217. |                   uppercase and the rest to lowercase, ie. STRCAP
  218. |                   TALLINIEMI = Talliniemi
  219.  
  220.                   Example 1 :
  221.  
  222.                     VAR %test% = STRING 35
  223.                     write "^C15;Please enter your name: ^C14,1;^L35;^C15;^M;"
  224.                     SET %test% = @ANSWER@
  225.                     write "^C14;You entered: %test%^M;"
  226.                     quit
  227.  
  228.                   Example 2 :
  229.  
  230.                     SET @HOTKEYS@ = OFF
  231.                     SET @SECLVL@  = 32000
  232.                     quit
  233.  
  234.                   Example 3:
  235.  
  236.                     VAR %totalmsgs% = NUMBER
  237.                     SET %totalmsgs% = (@PUBLICMSGS@+@PRIVATEMSGS@)
  238.                     write "^C15,0;You have written %totalmsgs% messages.^M;"
  239.                     quit
  240.  
  241.                   Example 4:
  242.  
  243.                     VAR %str% = STRING 10
  244.                     VAR %len% = NUMBER
  245.                     SET %str% = STRCPY 6 10 Pasi Talliniemi
  246.                     SET %len% = STRLEN %str%
  247.                     write "^C14,0;%str% (length %len%)^M;"
  248.                     quit
  249.   
  250.   --- Information about Concord Script Language ----------------------[ 6/8 ]--
  251.  
  252.  
  253.           WRITE <string>
  254.           OUTPUT [>][<filename>]
  255.           OUTPUT [<device>]
  256.  
  257.                   WRITE outputs given string. By default, this happens to
  258.                   console. It can be changed with OUTPUT command which
  259.                   redirects output to given destination (generally into
  260.                   ASCII text file). When writing to console, normal screen
  261.                   macros can be used, eg. ^M; sends linefeed and ^E1;
  262.                   clears screen. Optional ">" char before filename
  263.                   overwrites existing file instead of appending.
  264.  
  265.                   Example :
  266.  
  267.                     WRITE "^C14,0;This comes to screen.^M;"
  268.                     OUTPUT SCRIPT.LOG
  269.                     WRITE "@CURRDATE@ @CURRTIME@  @NAME@ was here.^M;"
  270.                     OUTPUT
  271.                     WRITE "^C14,0;Now returning to board...^M;"
  272.                     quit
  273.  
  274.           EXEC <cmdline>
  275.  
  276.                   EXEC shells to operating system and runs given command
  277.                   line. All normal MENU_EXEC parameters can be used, eg.
  278.                   *B is current bps rate and *T is user's time left.
  279.  
  280.                   Example :
  281.  
  282.                     EXEC c:\doors\xoremote.exe *P *G *D1- *D2- *E-
  283.                     quit
  284.  
  285.           MENUTYPE <num> <params>
  286.  
  287.                   MENUTYPE runs given menutype with given parameters. All
  288.                   menutypes are valid.
  289.  
  290.                   Example :
  291.  
  292.                     MENUTYPE 5 WELCOME.ANS
  293.                     MENUTYPE 5 /NEW NEWS.ANS
  294.                     quit
  295.   
  296.   --- Information about Concord Script Language ----------------------[ 7/8 ]--
  297.  
  298.  
  299.           IF
  300.           ELSE
  301.           END
  302.  
  303.                   IF-ELSE-END allows creating conditional loops where
  304.                   IF-loop is executed only if IF-statement is TRUE and
  305.                   ELSE-loop if IF-statement is FALSE. These can be one
  306.                   within another. ELSE branch is optional.
  307.  
  308.                   Example 1 :
  309.  
  310.                     IF (@SECLVL@ = 32000)
  311.                       write "^C14,0;You must be sysop!^M;"
  312.                     ELSE
  313.                       write "^C15,0;Your security level is @seclvl@^M;"
  314.                     END
  315.                     quit
  316.  
  317.                   Example 2 :
  318.  
  319.                     IF (@TAGFILES_COUNT@ > 0)
  320.                       write "^C12,0;You have flagged files to download.^M;"
  321.                     END
  322.                     quit
  323.  
  324.                   Example 3 :
  325.  
  326.                     write "Sysops only: do you want to continue? "
  327.                     write "(~1Y/~2n) ^W;^M;"
  328.                     IF ((@ANSWER@ = 1) AND (@SECLVL@ = 32000))
  329.                       write "Haha, nothing really important here...^M;"
  330.                     ELSE
  331.                       IF (@ANSWER@ <> 1)
  332.                         write "Wise choice...^M;"
  333.                       END
  334.                     END
  335.                     quit
  336.  
  337.           INPUT <filename>
  338.  
  339.                   Opens file <filename> for input. File can be read with
  340.                   macros @INPUT_NEXT@ and @INPUT_PREV@. Current file
  341.                   position is reported (and can be modified) in macro
  342.                   @INPUT_POS@. Input file size is reported in macro
  343.                   @INPUT_SIZE@ (-1=file not open).
  344.  
  345.   
  346.   --- Information about Concord Script Language ----------------------[ 8/8 ]--
  347.  
  348.  
  349.   Examples :
  350.  
  351. |         See *.SCR for example scripts.
  352.  
  353.   Notes :
  354.  
  355.   - Calculating : Works only with %VARIABLES% (not @CONSTANTS@). Always
  356.     remember to use () chars around formula...
  357.  
  358. | - If one comparison variable is number and the other is string,
  359. |   a string comparison will be performed.
  360.  
  361.   - String / Date / Time comparing : Always use double quotes (") around
  362.     variables. For example,
  363.  
  364.     VAR %STR1% = STRING 5
  365.     VAR %STR2% = STRING 5
  366.     SET %STR1% = STRCPY 1 5 @BIRTHDAY@
  367.     SET %STR2% = STRCPY 1 5 @CURRDATE@
  368.     IF ("%STR1%"="%STR2%")
  369.       WRITE "HAPPY BIRTHDAY!^M;"
  370.     END
  371.  
  372.   <end of document>
  373.